---
title: "Pagination"
description: "The Pagination component allows you to display active page and navigate between multiple pages."
---

import {paginationContent} from "@/content/components/pagination";

# Pagination

The Pagination component allows you to display active page and navigate between multiple pages.

<ComponentLinks component="pagination" />

---

<CarbonAd/>

## Installation

<PackageManagers
  showGlobalInstallWarning
  commands={{
    cli: "npx heroui-cli@latest add pagination",
    npm: "npm install @heroui/pagination",
    yarn: "yarn add @heroui/pagination",
    pnpm: "pnpm add @heroui/pagination",
    bun: "bun add @heroui/pagination"
  }}
/>

## Import

HeroUI exports 3 pagination-related components:

- **Pagination**: The main component to display a pagination.
- **PaginationItem**: The internal component to display a pagination item.
- **PaginationCursor**: The internal item component to display the current page.

<ImportTabs
  commands={{
    main: 'import {Pagination, PaginationItem, PaginationCursor} from "@heroui/react";',
    individual:
      'import {Pagination, PaginationItem, PaginationCursor} from "@heroui/pagination";',
  }}
/>

## Usage

<CodeDemo title="Usage" files={paginationContent.usage} />

### Disabled

<CodeDemo title="Disabled" files={paginationContent.disabled} />

### Sizes

<CodeDemo title="Sizes" files={paginationContent.sizes} />

### Colors

<CodeDemo title="Radius" files={paginationContent.colors} />

### Variants

You can use the `variant` property to change the pagination items style.

<CodeDemo title="Variants" files={paginationContent.variants} />

### With Controls

You can set the `showControls` to `true` to display the `next` and `previous` buttons.

<CodeDemo title="With Controls" files={paginationContent.controls} />

### Pagination Loop

In case you want to loop the pagination, you can set the `loop` property to `true`.
The cursor will go back to the first page when it reaches the last page and vice versa.

<CodeDemo title="Pagination Loop" files={paginationContent.loop} />

### Changing the initial page

You can change the initial page by setting the `initialPage` property.

<CodeDemo title="Changing the initial page" files={paginationContent.initialPage} />

### Compact Pagination

You can set the `isCompact` property to `true` to display reduced version of the pagination.

<CodeDemo title="Compact Pagination" files={paginationContent.compact} />

### With Shadow

You can use the `showShadow` property to display a shadow below the active page item.

<CodeDemo title="With Shadow" files={paginationContent.shadow} />

### Controlled

<CodeDemo title="Controlled" files={paginationContent.controlled} />

### Siblings

You can control the number of pages to show before and after the current page by setting the `siblings` property.

<CodeDemo title="Siblings" files={paginationContent.siblings} />

### Boundaries

You can control the number of pages to show at the beginning and end of the pagination by setting the `boundaries` property.

<CodeDemo title="Boundaries" files={paginationContent.boundaries} />

### Custom items

You can use the `renderItem` property to customize the pagination items.

<CodeDemo title="Custom items" files={paginationContent.customItems} />

## Slots

- **base**: The main pagination slot.
- **wrapper**: The pagination wrapper slot. This wraps the pagination items.
- **prev**: The previous button slot.
- **next**: The next button slot.
- **item**: The pagination item slot, applied to the middle items.
- **cursor**: The current page slot. Available only when `disableCursorAnimation` is `false` and `disableAnimation` is `false`.
- **forwardIcon**: The forward icon slot. The one that appears when hovering the ellipsis button.
- **ellipsis**: The ellipsis slot.
- **chevronNext**: The chevron next icon slot.

### Custom Styles

You can customize the `Pagination` component by passing custom Tailwind CSS classes to the component slots.

<CodeDemo title="Custom Styles" files={paginationContent.customStyles} />

### Custom Implementation

In case you need to customize the pagination even further, you can use the `usePagination` hook to create
your own implementation.

<CodeDemo title="Custom Implementation" files={paginationContent.customImpl} /> 

<Spacer y={4} />

## Data Attributes

`Pagination` has the following attributes on the `base` element:

- **data-controls**:
  Indicates whether the pagination has controls. Based on `showControls` prop.
- **data-loop**:
  When the pagination is looped. Based on `loop` prop.
- **data-dots-jump**:
  Indicates whether the pagination has dots jump. Based on `dotsJump` prop.
- **data-total**:
  The total number of pages. Based on `total` prop.
- **data-active-page**:
  The active page. Based on `activePage` prop.

<Spacer y={4} />

## Accessibility

- The root node has a role of `navigation` by default.
- The pagination items have an aria-label that identifies the item purpose ("next page button", "previous page button", etc.), you
  can override this label by using the `getItemAriaLabel` function.
- The pagination items are in tab order, with a tabindex of "0".

<Spacer y={4} />

## API

### Pagination Props

<APITable
  data={[
    {
      attribute: "variant",
      type: "flat | bordered | light | faded",
      description: "The pagination variant.",
      default: "flat"
    },
    {
      attribute: "color",
      type: "default | primary | secondary | success | warning | danger",
      description: "The pagination color theme.",
      default: "default"
    },
    {
      attribute: "size",
      type: "sm | md | lg",
      description: "The pagination size.",
      default: "md"
    },
    {
      attribute: "radius",
      type: "none | sm | md | lg | full",
      description: "The pagination border radius.",
      default: "xl"
    },
    {
      attribute: "total",
      type: "number",
      description: "The total number of pages.",
      default: "1"
    },
    {
      attribute: "dotsJump",
      type: "number",
      description: "The number of pages that are added or subtracted on the '...' button.",
      default: "5"
    },
    {
      attribute: "initialPage",
      type: "number",
      description: "The initial page. (uncontrolled)",
      default: "1"
    },
    {
      attribute: "page",
      type: "number",
      description: "The current page. (controlled)",
      default: "-"
    },
    {
      attribute: "siblings",
      type: "number",
      description: "The number of pages to show before and after the current page.",
      default: "1"
    },
    {
      attribute: "boundaries",
      type: "number",
      description: "The number of pages to show at the beginning and end of the pagination.",
      default: "1"
    },
    {
      attribute: "loop",
      type: "boolean",
      description: "Whether the pagination should be looped.",
      default: "false"
    },
    {
      attribute: "isCompact",
      type: "boolean",
      description: "Whether the pagination should have a compact style.",
      default: "false"
    },
    {
      attribute: "isDisabled",
      type: "boolean",
      description: "Whether the pagination is disabled.",
      default: "false"
    },
    {
      attribute: "showShadow",
      type: "boolean",
      description: "Whether the pagination cursor should have a shadow.",
      default: "false"
    },
    {
      attribute: "showControls",
      type: "boolean",
      description: "Whether the pagination should have controls.",
      default: "false"
    },
    {
      attribute: "disableCursorAnimation",
      type: "boolean",
      description: "Whether the pagination cursor should be hidden.",
      default: "false"
    },
    {
      attribute: "disableAnimation",
      type: "boolean",
      description: "Whether the pagination cursor should be animated.",
      default: "false"
    },
    {
      attribute: "renderItem",
      type: "PaginationItemProps",
      description: "The pagination item render function.",
      default: "-"
    },
    {
      attribute: "getItemAriaLabel",
      type: "(page: string) => string",
      description: "A function that allows you to customize the pagination items aria-label.",
      default: "-"
    },
    {
      attribute: "classNames",
      type: "Partial<Record<'base' | 'wrapper' | 'prev' | 'next' | 'item' | 'cursor' | 'forwardIcon' | 'ellipsis' | 'chevronNext', string>>",
      description: "Allows to set custom class names for the pagination slots.",
      default: "-"
    }
  ]}
/>

### Pagination Events

<APITable
  data={[
    {
      attribute: "onChange",
      type: "(page: number) => void",
      description: "Handler that is called when the pagination active page changes.",
      default: "-"
    }
  ]}
/>

---

### Types

#### Pagination Item Props

```ts
export type PaginationItemRenderProps = {
  // The pagination item ref.
  ref?: Ref<T>;
  // The pagination item value.
  value: PaginationItemValue;
  // The pagination item index.
  index: number;
  // The active page number.
  activePage: number;
  // Whether the pagination item is active.
  isActive: boolean;
  // Whether the pagination item is the first item in the pagination.
  isFirst: boolean;
  // Whether the pagination item is the last item in the pagination.
  isLast: boolean;
  // Whether the pagination item is the next item in the pagination.
  isNext: boolean;
  // Whether the pagination item is the previous item in the pagination.
  isPrevious: boolean;
  // The pagination item className.
  className: string;
  // Callback to go to the next page.
  onNext: () => void;
  // Callback to go to the previous page.
  onPrevious: () => void;
  // Callback to go to the page.
  setPage: (page: number) => void;
};

type renderItem?: (props: PaginationItemRenderProps) => ReactNode;
```
